﻿#region Copyright & License
//
// Project: Quark Framework
// Project site: http://quark.codeplex.com
// See the copyright statement on the project site for more details.
//
// Licensed to the Apache Software Foundation (ASF) under one or more 
// contributor license agreements. See the NOTICE file distributed with
// this work for additional information regarding copyright ownership. 
// The ASF licenses this file to you under the Apache License, Version 2.0
// (the "License"); you may not use this file except in compliance with 
// the License. You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
#endregion

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using Quark.Framework.Exceptions;

namespace Quark.Framework
{
    /// <summary>
    /// 表示对象实例具有独立的线程运行功能的接口
    /// </summary>
    /// <remarks>
    /// <list type=" number">
    /// <listheader>
    /// <term>创建对象实例后，其所实现的接口在容器中被调用顺序依次为：</term>
    /// </listheader>
    /// <item>
    /// <term><see cref="IInitializable.InitializeInstance()"/></term>
    /// <description>初始化对象实例</description>
    /// </item>
    /// <item>
    /// <term><see cref="IContextualizable.Contextualize(IQuarkContext)"/></term>
    /// <description>将对象实例置入上下文环境</description>
    /// </item>
    /// <item>
    /// <term><see cref="IConfigurable.Configure(IConfiguration)"/></term>
    /// <description>初始化对象实例的配置</description>
    /// </item>
    /// <item>
    /// <term><see cref="IStartable.StartRun()"/></term>
    /// <description>启动对象实例</description>
    /// </item>
    /// </list>
    /// </remarks>
    public interface IStartable
    {
        /// <summary>
        /// 获取当前对象实例是否已经被成功启动，
        /// 未启动或启动后被停止运行，都将返回false
        /// </summary>
        /// <query/>
        /// <threadsafety/>
        bool IsRunning { get; }

        /// <summary>
        /// 启动线程运行
        /// </summary>
        /// <exception cref="StartRunException">对象实例启动运行发生异常，内部抛出的异常统一以<see cref="StartRunException"/>作为异常封装</exception>
        /// <threadsafety/>
        void StartRun();

        /// <summary>
        /// 停止当前对象实例的线程运行，本方法发出停止信号后立即返回，并不代表线程会立即被停止运行，
        /// 可通过挂接事件代理<see cref="IStartable.OnStopped"/>来确保在线程停止时获得通知
        /// </summary>
        /// <exception cref="StopRunException">对象实例停止运行发生异常，内部抛出的异常统一以<see cref="StopRunException"/>作为异常封装</exception>
        /// <threadsafety/>
        void StopRun();

        /// <summary>
        /// 当前对象实例成功启动后触发的事件
        /// </summary>
        event StartableStartedHandler OnStarted;
        /// <summary>
        /// 当前对象实例运行被成功停止后触发的事件
        /// </summary>
        event StartableStoppedHandler OnStopped;
    }

    /// <summary>
    /// <see cref="IStartable"/>接口实例成功启动后触发的事件代理
    /// </summary>
    /// <param name="sender"><see cref="IStartable"/>接口实例</param>
    public delegate void StartableStartedHandler(IStartable sender);
    /// <summary>
    /// <see cref="IStartable"/>接口实例停止运行后触发的事件代理
    /// </summary>
    /// <param name="sender"><see cref="IStartable"/>接口实例</param>
    public delegate void StartableStoppedHandler(IStartable sender);
}
